What the mismatch is. The PR title ("feat(client): SEP-2350 scope step-up — union, retry cap, superset-gated refresh bypass") and the entire PR description claim a scope step-up feature: an onInsufficientScope option on both HTTP transports, exported computeScopeUnion() and InsufficientScopeError, an examples/scoped-tools headless story with a hardened demo AS, conformance-fixture withOAuthRetry wiring, and client-auth:step-up:* e2e scenarios. None of that content is present in this PR. The diff (and this changeset, .changeset/auth-dcr-hygiene.md) implements SEP-837/SEP-2207 Dynamic Client Registration hygiene instead: resolveClientMetadata() with application_type/grant_types defaults, RegistrationRejectedError, InsecureTokenEndpointError + assertSecureTokenEndpoint(), OAuthErrorCode.InvalidRedirectUri, and the matching e2e/conformance updates.\n\nStep-by-step verification at the PR head. (1) The changeset bot reports the PR's latest commit as 52b1cfca1d5a625d82aec89f373d0db4be4ffca3, which is exactly HEAD of this changeset, so this is not a stale-checkout artifact. (2) Grepping packages/client/src at that commit for computeScopeUnion, InsufficientScopeError (the transport-level class), onInsufficientScope, or _stepUpAuthorize returns no matches. (3) examples/scoped-tools does not exist, and the 18 changed files include no streamableHttp.ts, sse.ts, or test/conformance/src changes. (4) The new e2e scenarios are client-auth:dcr:*, client-auth:token-endpoint:https-guard, client-auth:refresh:rotation-handling, and client-auth:scope:offline-access-gate — not the client-auth:step-up:* rows the description claims under How Has This Been Tested. (5) The expected-failures edits remove SEP-837 application_type baseline entries; auth/scope-step-up remains baselined on the 2026-07-28 leg, contradicting the description's claim that it "burns" with this change. (6) The HEAD commit message itself reads "feat(client): SEP-837/2207 — application_type heuristic, grant_types default, https token-endpoint guard", matching the diff.\n\nWhy nothing else catches it. The earlier claude[bot] review comments referencing _stepUpAuthorize at an older head (8b2f271) indicate the branch previously carried the SEP-2350 work and was later force-pushed to the DCR-hygiene stack without updating the PR title/description. CI passes because the code that is present is internally consistent — there is no automated check that the description matches the diff.\n\nImpact. Reviewers approving this PR based on the description would be approving claims about transport behavior, breaking-change posture ("onInsufficientScope defaults to 'reauthorize'"), and testing evidence (step-up e2e scenarios, the conformance auth/scope-step-up burn) that the diff does not back. On squash-merge the description typically becomes the merge-commit body, permanently misdescribing what landed; future readers tracing SEP-2350 vs SEP-837/2207 history will be pointed at the wrong commit.\n\nHow to fix. Either (a) rewrite the PR title and description to describe the SEP-837/SEP-2207 DCR-hygiene change actually contained — the changeset text and the HEAD commit message are accurate starting points — including correcting the testing section to the client-auth:dcr:* / token-endpoint:https-guard scenarios and the SEP-837 expected-failures burn-down, or (b) push the intended SEP-2350 step-up commits to this branch if this PR was meant to carry them. This is an editorial/process issue rather than a code defect, but the description-vs-diff mismatch is total and should be resolved before merge.

What is stale. The @remarks on the OAuthClientFlowError base class near the top of packages/client/src/client/authErrors.ts reads: "Nothing in the SDK throws this base class directly. In the release that introduces it no subclass exists yet — the guard is a forward-compat hook and will not match anything until the first behavior change ships." The first sentence is still true; the second is now plainly false.

Why this PR makes it false. This PR adds two concrete subclasses to the same module, a few lines below that remark: RegistrationRejectedError (thrown by registerClient() when the AS rejects DCR) and InsecureTokenEndpointError (thrown by assertSecureTokenEndpoint() on the exchange/refresh/cross-app paths). Together with the pre-existing IssuerMismatchError (added in 318fca3), the family now has three shipped, actively-thrown members — so the instanceof OAuthClientFlowError guard the remark says "will not match anything" matches real errors the SDK throws on common paths.

Why it contradicts the PR's own docs. The migration-SKILL.md hunk added in this same PR publishes a three-row table of OAuthClientFlowError subclasses and their throw sites and explicitly recommends that consumers dispatch on them ("all extend OAuthClientFlowError, not OAuthError"). A reader who hovers the base class in their IDE sees JSDoc claiming the family is empty, while the migration guide shipped by the same PR tells them to catch its members.

Step-by-step. (1) Commit 874ca25 introduced OAuthClientFlowError with this remark, which was accurate at that moment (no subclasses). (2) Commit 318fca3 added IssuerMismatchError, making the remark stale. (3) This PR adds RegistrationRejectedError and InsecureTokenEndpointError directly below the remark and adds the consumer-facing subclass table — extending exactly the pattern the remark denies, in the same file, without updating it.

Impact. Documentation-only; no behavioral effect. The cost is reader confusion: the JSDoc actively tells consumers the catch-all guard is inert, which could discourage them from using the very instanceof dispatch the migration guide recommends.

How to fix. One-sentence JSDoc edit: delete the second @remarks sentence, or rewrite it to reflect reality, e.g. "Concrete subclasses currently include IssuerMismatchError, RegistrationRejectedError, and InsecureTokenEndpointError; catch the base class to handle the whole family." Since this PR touches the same file and adds the subclasses, this is the natural diff in which to make the change (the staleness technically began one commit earlier, but the PR directly compounds it).